<!--
-File         $Id: GettingStarted.html 1338 2011-10-28 20:40:34Z mrook $
-License      GNU FDL (http://www.gnu.org/copyleft/fdl.html)
-Copyright    2002, turing
-Author       alex black, enigma@turingstudio.com
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Phing Guide - Getting Started</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link rel="Stylesheet" rev="Stylesheet" href="../css/Documentation.css"
	type="text/css" media="All" charset="iso-8859-1" />
</head>
<body>

	<h1>
		<a name="GettingStarted"></a>Getting Started
	</h1>

	<p>Phing buildfiles are written in XML, and so you will need to
		know at least some basic things about XML to understand the following
		chapter. There is a lot of information available on the web:</p>

	<ul>
		<li>The Standard Recommendation of XML by the w3c <a
			href="http://www.w3.org/TR/2000/REC-xml">http://www.w3.org/TR/2000/REC-xml</a>:
			very technical but exhaustive.</li>
		<li><em>XML In 10 Points</em> <a
			href="http://www.w3.org/XML/1999/XML-in-10-points">http://www.w3.org/XML/1999/XML-in-10-points</a>:
			Quick introduction into XML.</li>
		<li><em>A technical introduction to XML</em> <a
			href="http://www.xml.com/pub/a/98/10/guide0.html">http://www.xml.com/pub/a/98/10/guide0.html</a>:
			Interesting article by the creator of DocBook.</li>
	</ul>

	<h2>
		<a name="XMLAndPhing"></a>XML And Phing
	</h2>

	<p>A valid Phing buildfile has the following basic structure:</p>


	<ul>
		<li>The document prolog</li>
		<li>Exactly one root element called <em>&lt;project&gt;</em> .</li>
		<li>Several Phing <em>type</em> elements (i.e. <em>&lt;property&gt;</em>
			, <em>&lt;fileset&gt;</em> , <em>&lt;patternset&gt;</em> etc.)</li>
		<li>One or more <em>&lt;target&gt;</em> elements containing
			built-in or user defined Phing <em>task</em> elements (i.e. <em>&lt;install&gt;</em>
			, <em>&lt;bcc&gt;</em> , etc).</li>
	</ul>

	<h2>
		<a name="WritingASimpleBuildfile"></a>Writing A Simple Buildfile
	</h2>

	<p>The Foobar project installs some PHP files from a source
		location to a target location, creates an archive of this files and
		provides an optional clean-up of the build tree:</p>

	<pre title="Example of a simple build file">
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;

&lt;project name=&quot;FooBar&quot; default=&quot;dist&quot;&gt;

    &lt;!-- ============================================  --&gt;
    &lt;!-- Target: prepare                               --&gt;
    &lt;!-- ============================================  --&gt;
    &lt;target name=&quot;prepare&quot;&gt;
        &lt;echo msg=&quot;Making directory ./build&quot; /&gt;
        &lt;mkdir dir=&quot;./build&quot; /&gt;
    &lt;/target&gt;

    &lt;!-- ============================================  --&gt;
    &lt;!-- Target: build                                 --&gt;
    &lt;!-- ============================================  --&gt;
    &lt;target name=&quot;build&quot; depends=&quot;prepare&quot;&gt;
        &lt;echo msg=&quot;Copying files to build directory...&quot; /&gt;

        &lt;echo msg=&quot;Copying ./about.php to ./build directory...&quot; /&gt;
        &lt;copy file=&quot;./about.php&quot; tofile=&quot;./build/about.php&quot; /&gt;

        &lt;echo msg=&quot;Copying ./browsers.php to ./build directory...&quot; /&gt;
        &lt;copy file=&quot;./browsers.php&quot; tofile=&quot;./build/browsers.php&quot; /&gt;

        &lt;echo msg=&quot;Copying ./contact.php to ./build directory...&quot; /&gt;
        &lt;copy file=&quot;./contact.php&quot; tofile=&quot;./build/contact.php&quot; /&gt;
    &lt;/target&gt;

    &lt;!-- ============================================  --&gt;
    &lt;!-- (DEFAULT)  Target: dist                       --&gt; 
    &lt;!-- ============================================  --&gt;
    &lt;target name=&quot;dist&quot; depends=&quot;build&quot;&gt;
        &lt;echo msg=&quot;Creating archive...&quot; /&gt;

        &lt;tar destfile=&quot;./build/build.tar.gz&quot; compression=&quot;gzip&quot;&gt;
            &lt;fileset dir=&quot;./build&quot;&gt;
                &lt;include name=&quot;*&quot; /&gt;
            &lt;/fileset&gt;
        &lt;/tar&gt;

        &lt;echo msg=&quot;Files copied and compressed in build directory OK!&quot; /&gt;
    &lt;/target&gt;
&lt;/project&gt;
</pre>
	<p>
		A phing build file is normally given the name <i>build.xml</i> which
		is the default file name that the Phing executable will look for if no
		other file name is specified.
	</p>
	<p>
		To run the above build file and execute the default target (assuming
		it is stored in the current directory with the default name) is only a
		matter of calling:
		<code> $ phing </code>
	</p>

	<p>
		This will then execute the <i>dist</i> target. While executing the
		build file each task performed will print some information on what
		actions and what files have been affected.
	</p>
	<p>
		To run any of the other target is only a matter of providing the name
		of the target on the command line. So for example to run the <i>build</i>
		target one would have to execute
		<code> $ phing build </code>
	</p>

	<p>
		It is also possible to specify a number of additional command line
		arguments as described in <a
			href="appendixes/AppendixA-FactSheet.html#BuildInProperties">Appendix
			A</a>
	</p>

	<h3>
		<a name="ProjectElement"></a>Project Element
	</h3>

	<p>
		The first element after the document prolog is the root element named
		<em>&lt;project&gt;</em> on line 3. This element is a container for
		all other elements and can/must have the following attributes:
	</p>

	<table>
		<caption>&lt;project&gt; Attributes</caption>

		<thead>
			<tr>
				<th>Attribute</th>
				<th>Meaning</th>
				<th>Required</th>
			</tr>
		</thead>

		<tbody>
			<tr>
				<td>name</td>
				<td>The name of the project</td>
				<td>No</td>
			</tr>
			<tr>
				<td>basedir</td>
				<td>The base directory of the project, use &quot;.&quot; do
					denote the current directory. <strong>Note:</strong> if none is
					specified, the parent directory of the build file is used!</td>
				<td>No</td>
			</tr>
			<tr>
				<td>default</td>
				<td>The default target that is to be executed if no target(s)
					are specified when calling this build file.</td>
				<td>Yes</td>
			</tr>
			<tr>
				<td>description</td>
				<td>The description of the project.</td>
				<td>No</td>
			</tr>
		</tbody>

	</table>

	<h3>
		<a name="TargetElement"></a>Target Element
	</h3>

	<p>
		A target can <em>depend</em> on other targets. You might have a target
		for installing the files in the build tree, for example, and a target
		for creating a distributable tar.gz archive. You can only build a
		distributable when you have installed the files first, so the
		distribute target depends on the install target. Phing resolves these
		dependencies.
	</p>

	<p>It should be noted, however, that Phing's depends attribute only
		specifies the order in which targets should be executed - it does not
		affect whether the target that specifies the dependency(s) gets
		executed if the dependent target(s) did not (need to) run.</p>

	<p>Phing tries to execute the targets in the depends attribute in
		the order they appear (from left to right). Keep in mind that it is
		possible that a target can get executed earlier when an earlier target
		depends on it, in this case the dependant is only executed once:</p>

	<pre>
	&lt;target name="A" /&gt;
	
	&lt;target name="B" depends="A" /&gt;

	&lt;target name="C" depends="B" /&gt;
	
    &lt;target name="D" depends="C,B,A" /&gt;
</pre>

	<p>
		Suppose we want to execute target
		<tt>D</tt>
		. From its depends attribute, you might think that first target
		<tt>C</tt>
		, then
		<tt>B</tt>
		and then
		<tt>A</tt>
		is executed. Wrong!
		<tt>C</tt>
		depends on
		<tt>B</tt>
		, and
		<tt>B</tt>
		depends on
		<tt>A</tt>
		, so first
		<tt>A</tt>
		is executed, then
		<tt>B</tt>
		, then
		<tt>C</tt>
		, and finally
		<tt>D</tt>
		.
	</p>

	<p>A target gets executed only once, even when more than one target
		depends on it (see the previous example).</p>

	<p>
		The optional description attribute can be used to provide a one-line
		description of this target, which is printed by the
		<tt>-projecthelp</tt>
		command-line option.
	</p>

	<h4>
		<a name="TargetAttributes"></a>Target attributes
	</h4>

	<p>You can specify one or more of the following attributes within
		the target element.</p>

	<table>
		<caption>&lt;target&gt; Attributes</caption>
		<thead>
			<tr>
				<th>Attribute</th>
				<th>Meaning</th>
				<th>Required</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td>name</td>
				<td>The name of the target</td>
				<td>Yes</td>
			</tr>
			<tr>
				<td>depends</td>
				<td>A comma-seperated list of targets this target depends on.</td>
				<td>No</td>
			</tr>
			<tr>
				<td>if</td>
				<td>The name of the <em>Property</em> that has to be set in
					order for this target to be executed</td>
				<td>No</td>
			</tr>
			<tr>
				<td>unless</td>
				<td>The name of the <em>Property</em> that must <em>not</em> be
					set in order for this target to be executed.</td>
				<td></td>
			</tr>
		</tbody>
	</table>

	<h3>
		<a name="TaskElements"></a>Task Elements
	</h3>

	<p>
		A <em>task</em> is a piece of PHP code that can be executed. This code
		implements a particular action to perform (i.e. install a file).
		Therefore it must be defined in the buildfile so that it is actually
		invoked by Phing.
	</p>

	<p>These references will be resolved before the task is executed.</p>

	<p>Tasks have a common structure:</p>

	<pre>
    &lt;name attribute1="value1" attribute2="value2" ... /&gt;
</pre>

	<p>
		where <em>name</em> is the name of the task, <em>attributeN</em> is
		the attribute name, and <em>valueN</em> is the value for this
		attribute.
	</p>

	<p>
		There is a set of core tasks (see <a
			href="appendixes/AppendixB-CoreTasks.html">Appendix B</a>) along with
		a number of optional tasks. It is also very easy to write your own
		tasks (see <a href="ExtendingPhing.html">Extending Phing</a>).
	</p>

	<p>
		Tasks can be assigned an <em>id</em> attribute:
	</p>

	<pre>
    &lt;taskname id="taskID" ... /&gt;
</pre>

	<p>By doing this you can refer to specific tasks later on in the
		code of other tasks.</p>


	<h3>
		<a name="PropertyElement"></a>Property Element
	</h3>

	<p>
		<em>Properties</em> are essentially variables that can be used in the
		buildfile. These might be set in the buildfile by calling the <a
			href="appendixes/AppendixB-CoreTasks.html#PropertyTask">PropertyTask</a>,
		or might be set outside Phing on the command line (properties set on
		the command line always override the ones in the buildfile). A
		property has a name and a value only. Properties may be used in the
		value of task attributes. This is done by placing the property name
		between &quot;
		<tt>${</tt>
		&quot; and &quot;
		<tt>}</tt>
		&quot; in the attribute value. For example, if there is a BC_BUILD_DIR
		property with the value 'build', then this could be used in an
		attribute like this: <em>${BC_BUILD_DIR}/en</em> . This is resolved to
		<em>build/en</em>.
	</p>

	<p>
		It should be noted that if you use a property that is not defined via
		the property task, the system environment table is searched for this
		name. For example, if you would use the property
		<tt>${BCHOME}</tt>
		and you did not define this prior in the buildfile or at the command
		line, Phing uses the environment variable
		<tt>BCHOME</tt>
		if it exists.
	</p>

	<h4>
		<a name="BuiltInProperties"></a>Built-in Properties
	</h4>

	<p>
		Phing provides access to system properties as if they had been defined
		using a <em>&lt;property&gt;</em> task. For example, <em>${os.name}</em>
		expands to the name of the operating system. See <a
			href="appendixes/AppendixA-FactSheet.html#BuildInProperties">Appendix
			A</a> for a complete list
	</p>


	<h2>
		<a name="ComplexBuildfile"></a>More Complex Buildfile
	</h2>

	<pre title="More complex build file">&lt;?xml version=&quot;1.0&quot;  encoding=&quot;UTF-8&quot; ?&gt;

&lt;project name=&quot;testsite&quot; basedir=&quot;.&quot; default=&quot;main&quot;&gt;
    &lt;property file=&quot;./build.properties&quot; /&gt;

    &lt;property name=&quot;package&quot;  value=&quot;${phing.project.name}&quot; override=&quot;true&quot; /&gt;
    &lt;property name=&quot;builddir&quot; value=&quot;./build/testsite&quot; override=&quot;true&quot; /&gt;
    &lt;property name=&quot;srcdir&quot;   value=&quot;${project.basedir}&quot; override=&quot;true&quot; /&gt;

    &lt;!-- Fileset for all files --&gt;
    &lt;fileset dir=&quot;.&quot; id=&quot;allfiles&quot;&gt;
        &lt;include name=&quot;**&quot; /&gt;
    &lt;/fileset&gt;

    &lt;!-- ============================================  --&gt;
    &lt;!-- (DEFAULT) Target: main                        --&gt;
    &lt;!-- ============================================  --&gt;
    &lt;target name=&quot;main&quot; description=&quot;main target&quot;&gt;
        &lt;copy todir=&quot;${builddir}&quot;&gt;
            &lt;fileset refid=&quot;allfiles&quot; /&gt;
        &lt;/copy&gt;
    &lt;/target&gt;

    &lt;!-- ============================================  --&gt;
    &lt;!-- Target: Rebuild                               --&gt;
    &lt;!-- ============================================  --&gt;
    &lt;target name=&quot;rebuild&quot; description=&quot;rebuilds this package&quot;&gt;
        &lt;delete dir=&quot;${builddir}&quot; /&gt;
        &lt;phingcall target=&quot;main&quot; /&gt;
    &lt;/target&gt;
&lt;/project&gt;
</pre>

	<p>
		This build file first defines some properties with the <em>&lt;property&gt;</em>
		task call to <em>PropertyTask</em>. Then, it defines a fileset and two
		targets. Let us have a quick rundown of this build file.
	</p>

	<p>
		The first five four within the <em>project</em> tag define properties.
		They appear in the two ways this tag can occur:
	</p>
	<ul>
		<li>The second <em>property</em> tag contains only the <em>file</em>
			attribute. The value has to be a relative or absolute path to a
			property file (for the format, see <a
			href="appendixes/AppendixF-FileFormats.html">Appendix F</a>).</li>
		<li>The other times, the tag has a <em>name</em> and a <em>value</em>
			attribute. After the call, the value defined in the attribute <em>value</em>
			is available through the key enclosed in &quot;${&quot; and
			&quot;}&quot;.</li>
	</ul>
	<p>
		The next noticeable thing in the build file is the <em>&lt;fileset&gt;</em>
		tag. It defines a fileset, i.e. a set of multiple files. You can
		include and exclude files with the <em>include</em> and <em>exclude</em>
		tags within the <em>fileset</em> tag. For more information concerning
		Filesets (i.e. Patterns) see <a
			href="appendixes/AppendixD-CoreTypes.html#Fileset">Appendix D</a>.
		The fileset is given an <em>id</em> attribute, so it can be referenced
		later on.
	</p>
	<p>
		One thing is worth noting here though and that is the use of double
		star expression, i.e. "**". This special regexp refers to all files in
		all subdirectories as well. Compare this with a single "*" which would
		only refer to all files in the <i>current</i> subdirectory. So for
		example the expression "**/*.phps" would refer to all files with
		suffix "'.phps" in all subdirectories below the current directory.
	</p>

	<p>
		The first task only contains a call to <em>CopyTask</em> via <em>&lt;copy&gt;</em>.
		The interesting thing is within the <em>copy</em> tag. Here, a fileset
		task is not written out with nested <em>include</em> or <em>exclude</em>
		elements, but via the <em>refid</em>, the Fileset created earlier is
		referenced. This way, you can use a once defined fileset multiple
		times in your build files.
	</p>

	<p>
		The only noticeable thing in the second target is the call to <em>PhingTask</em>
		with the <em>&lt;phingcall&gt;</em> tag (see <a
			href="appendixes/AppendixB-CoreTasks.html#PhingCallTask">Appendix
			B</a> for more information). The task executes a specified target within
		the same build file. So, the second target removes the build directory
		and calls <em>main</em> again, thus rebuilding the project.
	</p>

	<p>
		A variant is to override properties defined in the build file with
		properties specified on the command line using the <i>-D</i> switch.
		For example to override the <i>builddir</i> in the build file above
		one could call Phing as
		<code> $ phing -Dbuilddir=/tmp/system-test </code>
	</p>



	<h2>
		<a name="RelaxNGGrammar"></a>Relax NG Grammar
	</h2>

	<p>With a little bit of experience it is not that difficult to
		write and understand Phing build files since the XML format in itself
		tends to be quite verbose. However, it can become a bit tedious and
		the large (and growing) amount of built-in tasks and filters can
		sometimes make it difficult to remember the exact syntax of all the
		available features.</p>
	<p>
		To help with this the Phing distribution contains a <i>Relax NG
			Grammar</i> (<b>RE</b>gular <b>LA</b>nguage for <b>X</b>ML <b>N</b>ext <b>G</b>eneration,
		<a href="http://www.relaxng.org/">http://www.relaxng.org/</a>) that
		describes the (formal) syntax of the build files. This grammar can
		help validate and write Phing build files since there are many XML
		editors which can make use of this type of grammar to validate, on the
		fly, as well as do context-sensitive auto-completion. Especially the
		auto-complete feature can significantly reduce the time it takes to
		write a correct, and possible complex, Phing build files.
	</p>
	<p>
		This grammar is available (as a plain text file) in the distribution
		at:
		<code> /etc/phing-grammar.rng </code>
	</p>

	<p>Since we do not want to neither endorse nor forget any
		particular XML editor with this capability we do not make available
		such a list of editors. Instead, spending a few minutes with Google
		searching for XML-editors is bound to find a number of editors with
		this capability.</p>
	
	<p>If you wish to validate your Phing build file, there are numerous
		options. Links to various validation tools and XML editors
		are available at the RELAX NG home page, <a
		href="http://www.relaxng.org/">http://www.relaxng.org/</a>.
		The command line tool <em>xmllint</em> that comes with
		libxml2 is also able to validate a given XML file
		against the supplied grammar.
	</p>
	<p>For example, to use xmllint to validate a Phing build file the
		following command line could be used:</p>
	<pre>
$ xmllint -noout -relaxng phing-grammar.rng build.xml
build.xml validates
$
</pre>
</body>
</html>
